document the delete organization sub account endpoint - #56

Motivation

Sub-accounts can now be deleted from the organization panel, and the same action is exposed over
the public API. DELETE /api/organizations/{organization_id}/sub_accounts/{sub_account_id} is not
described in the spec yet, so it is missing from the rendered reference.

Changes

• deleteOrganizationSubAccount: new delete operation on
  /api/organizations/{organization_id}/sub_accounts/{sub_account_id}, tagged Organizations,
  reusing the existing organization_id parameter and adding a shared sub_account_id one
  • 204 with no body on success, 401, 403 on insufficient organization permissions, another
    organization's organization_id or the Organization & Sub-accounts feature turned off,
    404 on an unknown, already deleted or other organization's sub-account,
    409 when a deletion for the same sub-account is already running, 429 over the rate limit of
    10 requests per minute per organization
  • the description states that the sub-account and its data are removed permanently, and that
    deleting the organization's last sub-account also deletes the organization
  • code samples for cURL, Node.js, PHP, Python, Ruby, .NET and Java, mirroring the create
    operation; the SDK methods land in the companion PRs below
• new RateLimitExceededResponse schema and LIMIT_EXCEEDED response for the 429, which the
  spec had no shared definition for
• the delete description asks for admin permissions for the organization; sub account
  management permissions are not enough

How to test

• the spec lints clean in CI
• in the rendered reference, Organizations shows "Delete organization sub account" with the
  organization_id and sub_account_id path params, cURL / Node.js / PHP / Python / Ruby /
  .NET / Java samples, and 204/401/403/404/409/429 responses
• the 429 example reads {"errors": "Rate limit exceeded"}
• against the deployed API: DELETE /api/organizations/:organization_id/sub_accounts/:id with
  a token holding Organization & Sub-accounts Admin returns 204 and the sub-account is gone
  from GET /api/organizations/:organization_id/sub_accounts
• the same DELETE on another sub-account with a token holding Sub-accounts Creation & Listing
  Admin returns 403, and the sub-account is still listed
• the same call repeated returns 404; with a viewer-level token 403; with no token 401
• the same DELETE with a sub-account id from another organization returns 404
• a second DELETE for the same sub-account while the first one is still in flight returns 409
  with {"errors": "Another action in progress. Wait until it's finished"}
• more than 10 calls within a minute for one organization return 429

Companion PRs

• backend endpoint (in production)
• add sub account deletion mailtrap-nodejs#159 – nodejs SDK
• add sub account deletion mailtrap-ruby#130 – ruby SDK
• Add SubAccountsApi.delete for DELETE /api/organizations/{id}/sub_accounts/{id} mailtrap-python#83 – python SDK
• Add deleteSubAccount for organization sub-accounts mailtrap-php#80 – php SDK
• add sub account deletion mailtrap-java#75 – java SDK
• add sub account deletion mailtrap-dotnet#259 – .NET SDK
• fix the permission note for deleting a sub-account mailtrap-go#41 – go SDK permission note (Delete shipped in v0.4.0)
• add sub-account deletion to the CLI mailtrap-cli#15 – CLI
• add delete-sub-account tool mailtrap-mcp#144 – MCP server